<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
 <head>
  <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  <title>Using Phar Archives: the Phar and PharData class</title>
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-base.css" />
<link media="all" rel="stylesheet" type="text/css" href="styles/03e73060321a0a848018724a6c83de7f-theme-medium.css" />

 </head>
 <body class="docs"><div class="navbar navbar-fixed-top">
  <div class="navbar-inner clearfix">
    <ul class="nav" style="width: 100%">
      <li style="float: left;"><a href="phar.using.stream.html">« Using Phar Archives: the phar stream wrapper</a></li>
      <li style="float: right;"><a href="phar.creating.html">Creating Phar Archives »</a></li>
    </ul>
  </div>
</div>
<div id="breadcrumbs" class="clearfix">
  <ul class="breadcrumbs-container">
    <li><a href="index.html">PHP Manual</a></li>
    <li><a href="phar.using.html">Using Phar Archives</a></li>
    <li>Using Phar Archives: the Phar and PharData class</li>
  </ul>
</div>
<div id="layout">
  <div id="layout-content"><div id="phar.using.object" class="section">
 <h2 class="title">Using Phar Archives: the Phar and PharData class</h2>
 <p class="para">
  The <span class="classname"><a href="class.phar.html" class="classname">Phar</a></span> class supports reading and manipulation
  of Phar archives, as well as iteration through inherited functionality of
  the <span class="classname"><a href="class.recursivedirectoryiterator.html" class="classname">RecursiveDirectoryIterator</a></span>
  class.  With support for the <span class="classname"><a href="class.arrayaccess.html" class="classname">ArrayAccess</a></span>
  interface, files inside a Phar archive can be accessed as if they were
  part of an associative array.
 </p>
 <p class="para">
  The <span class="classname"><a href="class.phardata.html" class="classname">PharData</a></span> class extends the <span class="classname"><a href="class.phar.html" class="classname">Phar</a></span>, and
  allows creating and modifying non-executable (data) tar and zip archives even if
  <code class="literal">phar.readonly</code>=1 in php.ini.  As such,
  <span class="function"><a href="phardata.setalias.html" class="function">PharData::setAlias()</a></span> and <span class="function"><a href="phardata.setstub.html" class="function">PharData::setStub()</a></span>
  are both disabled as the concept of alias and stub are unique to executable phar
  archives.
 </p>
 <p class="para">
  It is important to note that when creating a Phar archive, the full path
  should be passed to the <span class="classname"><a href="class.phar.html" class="classname">Phar</a></span> object constructor.
  Relative paths will fail to initialize.
 </p>
 <p class="para">
  Assuming that <code class="literal">$p</code> is a Phar object initialized as follows:
 </p>
 <p class="para">
  <div class="informalexample">
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br />$p&nbsp;</span><span style="color: #007700">=&nbsp;new&nbsp;</span><span style="color: #0000BB">Phar</span><span style="color: #007700">(</span><span style="color: #DD0000">'/path/to/myphar.phar'</span><span style="color: #007700">,&nbsp;</span><span style="color: #0000BB">0</span><span style="color: #007700">,&nbsp;</span><span style="color: #DD0000">'myphar.phar'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
 </p>
 <p class="para">
  An empty Phar archive will be created at <code class="literal">/path/to/myphar.phar</code>,
  or if <code class="literal">/path/to/myphar.phar</code> already exists, it will be opened
  again.  The literal <code class="literal">myphar.phar</code> demonstrates the concept of an alias
  that can be used to reference <code class="literal">/path/to/myphar.phar</code> in URLs as in:
 </p>
 <p class="para">
  <div class="informalexample">
   <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB">&lt;?php<br /></span><span style="color: #FF8000">//&nbsp;these&nbsp;two&nbsp;calls&nbsp;to&nbsp;file_get_contents()&nbsp;are&nbsp;equivalent&nbsp;if<br />//&nbsp;/path/to/myphar.phar&nbsp;has&nbsp;an&nbsp;explicit&nbsp;alias&nbsp;of&nbsp;"myphar.phar"<br />//&nbsp;in&nbsp;its&nbsp;manifest,&nbsp;or&nbsp;if&nbsp;the&nbsp;phar&nbsp;was&nbsp;initialized&nbsp;with&nbsp;the<br />//&nbsp;previous&nbsp;example's&nbsp;Phar&nbsp;object&nbsp;setup<br /></span><span style="color: #0000BB">$f&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">'phar:///path/to/myphar.phar/whatever.txt'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$f&nbsp;</span><span style="color: #007700">=&nbsp;</span><span style="color: #0000BB">file_get_contents</span><span style="color: #007700">(</span><span style="color: #DD0000">'phar://myphar.phar/whatever.txt'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?&gt;</span>
</span>
</code></div>
   </div>

  </div>
 </p>
 <p class="para">
  With the newly created <code class="literal">$p</code> <span class="classname"><a href="class.phar.html" class="classname">Phar</a></span> object,
  the following is possible:
  <ul class="itemizedlist">
   <li class="listitem">
    <span class="simpara">
     <code class="literal">$a = $p[&#039;file.php&#039;]</code> creates a <span class="classname"><a href="class.pharfileinfo.html" class="classname">PharFileInfo</a></span>
     class that refers to the contents of <code class="literal">phar://myphar.phar/file.php</code>
    </span>
   </li>
   <li class="listitem">
    <span class="simpara">
     <code class="literal">$p[&#039;file.php&#039;] = $v</code> creates a new file
     (<code class="literal">phar://myphar.phar/file.php</code>), or overwrites
     an existing file within <code class="literal">myphar.phar</code>.  <code class="literal">$v</code>
     can be either a string or an open file pointer, in which case the entire
     contents of the file will be used to create the new file.  Note that
     <code class="literal">$p-&gt;addFromString(&#039;file.php&#039;, $v)</code> is functionally
     equivalent to the above.  Also possible is to add the contents of a file
     with <code class="literal">$p-&gt;addFile(&#039;/path/to/file.php&#039;, &#039;file.php&#039;)</code>.
     Lastly, an empty directory can be created with
     <code class="literal">$p-&gt;addEmptyDir(&#039;empty&#039;)</code>.
    </span>
   </li>
   <li class="listitem">
    <span class="simpara">
     <code class="literal">isset($p[&#039;file.php&#039;])</code> can be used to determine
     whether <code class="literal">phar://myphar.phar/file.php</code> exists within
     <code class="literal">myphar.phar</code>.
    </span>
   </li>
   <li class="listitem">
    <span class="simpara">
     <code class="literal">unset($p[&#039;file.php&#039;])</code> erases
     <code class="literal">phar://myphar.phar/file.php</code> from
     <code class="literal">myphar.phar</code>.
    </span>
   </li>
  </ul>
 </p>
 <p class="para">
  In addition, the <span class="classname"><a href="class.phar.html" class="classname">Phar</a></span> object is the only way to access
  Phar-specific metadata, through
  <span class="function"><a href="phar.getmetadata.html" class="function">Phar::getMetadata()</a></span>,
  and the only way to set or retrieve a Phar archive&#039;s PHP loader stub through
  <span class="function"><a href="phar.getstub.html" class="function">Phar::getStub()</a></span> and
  <span class="function"><a href="phar.setstub.html" class="function">Phar::setStub()</a></span>.
  Additionally, compression for the entire Phar archive at once can only be manipulated
  using the <span class="classname"><a href="class.phar.html" class="classname">Phar</a></span> class.
 </p>
 <p class="para">
  The full list of <span class="classname"><a href="class.phar.html" class="classname">Phar</a></span> object functionality is documented
  below.
 </p>
 <p class="para">
  The <span class="classname"><a href="class.pharfileinfo.html" class="classname">PharFileInfo</a></span> class extends the
  <span class="classname"><a href="class.splfileinfo.html" class="classname">SplFileInfo</a></span>
  class, and adds several methods for manipulating Phar-specific details of a file
  contained within a Phar, such as manipulating compression and metadata.
 </p>
</div></div></div></body></html>